<!DOCTYPE html>
<html>
  <head>
    <title>project brookdale release notes</title>
    <link rel="stylesheet" type="text/css" href="css/default.css"/>
  </head>
  <body>
    <table>
      <tr>
	<td class="title">project brookdale release notes</td>
      </tr>
      <tr>
	<td class="content">
	  <h1>0. about this document</h1>
	  
	  <p>
	    these are the release notes for the initial checkin for the
	    <a href="http://code.google.com/p/brookdale">brookdale project</a>,
	    a sample implementation of the VWRAP protocol. these docs will
	    (hopefully) give you enough information to install and configure
	    a (very) basic VWRAP service set.
	  </p>

	  <p>
	    this document assumes the reader is familiar with web concepts
	    and protocols (like HTTP). it also assumes the reader is
	    familiar with basic unix administration. this code was developed
	    and tested on unix&trade; like systems, but it <em>may</em> work
	    on other posix compatible operating systems. your mileage may
	    vary.
	  </p>

	  <p>
	    the latest version of this document can be found at the brookdale
	    project website, referenced above.
	  </p>
	    
	  <h1>1. why should i care about the brookdale project?</h1>

	  <p>
	    the brookdale project provides a (very) basic implementation of
	    VWRAP protocols in PHP, JavaScript and C. (note that the initial
	    check-in contains only the PHP code.) VWRAP (aka the
	    <a href="https://datatracker.ietf.org/wg/vwrap/charter/">Virtual
	    Worlds Region Agent Protocol</a>) is an open standard being
	    developed under the auspices of the
	    <a href="http://ietf.org">Internet Engineering Task Force</a>
	    (IETF). it provides interoperabilty specifications for network
	    hosts collaborating to simulate a virtual world.
	  </p>

	  <p>
	    if you are crazy enough to want to develop code that implements a
	    virtual world, this is the project for you.
	  </p>

	  <h1>2. what is it?</h1>

	  <p>
	    the initial revision of this code provides a VWRAP-compatible
	    "service broker" written in PHP. a "service broker" is a
	    web application that maintains information about the virtual world.
	    please note, even though it's a web application, it does not
	    produce HTML and is not targeted at human users directly. instead,
	    virtual world client applications speak to the service broker
	    on the user's behalf.
	  </p>

	  <p>
	    in other words, this application spits out a lot of XML. if you
	    like looking at XML directly, you're certainly welcome to do so,
	    but keep in mind we're not expecting it to be interesting to
	    people or programs other than virtual world client applications.
	  </p>

	  <p>
	    if you read PHP code, you may be interested in looking at the
	    implementation. the code demonstrates the use of the Dynamic
	    Structured Data (DSD) facility which implements some of the
	    features described in the VWRAP DSD draft.
	  </p>

	  <h1>3. files you'll find included</h1>
	  
	  <p>here are some of the directories and files you'll find here:</p>

	  <p>
	    <pre>
/sql/           - a place to store some SQL files
/www/           - contains files to be served by apache
/www/index.html - this file
/www/a/         - the service broker application
/www/css/       - CSS for this file and the xhtml files generated via xslt
/www/xml/       - directory containing static XML files
/www/xml/dtd/   - directory containing static DTD files
/www/xml/xsl/   - directory for xsl files for converting XML files to xhtml
/www/xml/dsd/   - directory containing static DSDX files
	    </pre></p>

	  <h1>4. making it do something</h1>

	  <p>
	    before installing and configuring this app, you'll need the
	    following items:
	    <ul>
	      <li>
		a reasonably powerful computer running a reasonably 
		recent version of linux.
	      </li>
	      <li>
		a reasonably recent version of apache2. other web servers
		may work, but no promises.
	      </li>
	      <li>
		a reasonably recent mysql database
	      </li>
	      <li>
		a network connection
	      </li>
	    </ul>
	    okay. let's go!
	  </p>

	  <h2>4.1. creating the database</h2>
	  
	  <p>
	    before you can do anything with this app, you have to setup the
	    test database.
	    <ol>
	      <li>
		<p>log into a mysql instance with the command:<br/>
		<code><strong>mysql -u <em>username</em> -p</strong></code><br/>
		if your database system is configured to promt you for a
		password, it will do so at this time. go ahead and type in
		the password.</p>
	      </li>
	      <li>
		<p>create the brookdale with the command:<br/>
		<code><strong>create database brookdale;</strong></code></p>
	      </li>
	      <li>
		<p>exit the database by hitting the control-D key or by
		  entering the command:<br/>
		  <code><strong>exit</strong></code></p>
	      </li>
	      <li>
		<p>load the database schema with the command:<br/>
		  <code><strong>mysql -u <em>username</em> -p &lt;
		      schema.sql</strong></code></p>
               </li>
	      <li>
		<p>load the test database with the command:<br/>
		  <code><strong>mysql -u <em>username</em> -p &lt;
		      test.sql</strong></code></p>
               </li>

	    </ol>
	  </p>
	  
	  <h2>4.2 update the config file</h2>
	  
	  <p>
	    <ol>
	      <li>
		<p>change directories into the "a" directory and make a copy the
		  example local config file like this:<br/>
		  <code><strong>cp ExampleLocalConfig.php
		      LocalConfig.php</strong></code></p>
	      </li>

	      <li>
		<p>
		  edit the LocalConfig.php file, changing the hostname, username
		  password and database name for your mysql database.</p>
	      </li>
	    </ol>
	  </p>

	  <h2>4.3 see if it works</h2>
	  
	  <p>
	    the simplest way to see if things are working correctly is to
	    try to access the site_info resource at:<br/>
	    <a href="./a/site_info">./a/site_info</a>
	  </p>

	  <p>
	    the more adventurous may try to use wget to query the broker:<br/>
	    <code><strong>wget -O site_info.dsdx -S http://<em>hostname</em>/a/site_info</strong></code>.
	  </p>

	</td>
      </tr>
      <tr>
	<td class="footer">copyright &copy; 2010 meadhbh s. hamrick, all rights reserved</td>
      </tr>
    </table>
  </body>
</html>
